[% setvar title " %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>&quot;=for testing&quot; - Embedded tests</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Michael G Schwern &lt;<a href='mailto:schwern@pobox.com'>schwern@pobox.com</a>&gt;
  Date: 31 Aug 2000
  Mailing List: <a href='mailto:perl-qa@perl.org'>perl-qa@perl.org</a>
  Number: 183
  Version: 1
  Status: Developing</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Using &quot;=for testing&quot;, regression tests can be embedded in the code and
documentation near what they are testing.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>It's an old rule of thumb that documentation should be near the code it's
documenting.  This increases the likelyhood that the docs will be kept up to
date with the code.  This is one of the reasons we have POD.  Building on
that idea is that tests should also be near what it is testing.  This
involves embedding tests in the documentation.</p>
<pre>    =item B&lt;is_pirate&gt;

        @pirates = is_pirate(@arrrgs);

    Go through @arrrgs and return a list of pirates.

    =for testing

    my @p = is_pirate('Blargbeard', 'Alfonse', 'Capt. Hampton', 'Wesley');
    ok(@p == 2);

    =cut

    sub is_pirate {
        ....
    }</pre>
<p>&quot;=begin testing/=end testing&quot; will also be recognized as per the
normal POD rules for &quot;=begin/end&quot; blocks.</p>
<p>Either during the make process (via Makemaker), with a Pod::Tests
module, or a pod2tests utility, the POD will be scanned and all &quot;=for
testing&quot; blocks would be appended to a generated .t file in the t/
directory.  This .t file would then be run as part of a normal &quot;make
test&quot;.</p>
<p>Several utility functions will be provided to make the test author's
life easier.  ok() is one of them, providing a simple &quot;ok/not ok&quot;
output depending on the truth of the given expression.</p>
<p>By default, a seperate .t file for the tests will be generated.  This
file will be named based on the file from which it was generated.
Thus, &quot;lib/Some/Module.pm&quot; might generate &quot;t/Some-Module-embedded.t&quot;.
This .t file will start with the normal testing stub similar to that
provided by h2xs, as well as the mentioned utility routines.</p>
<p>If this is not to the author's liking, they may specify a specific
file where their tests are to go.</p>
<pre>    =for testing t/my_tests.t</pre>
<p>The filename is relative to the current working directory.  Embedded
tests which have filenames will simply be appended to that file.
Nothing else will be provided as it is assumed the author will handle
it.</p>
<a name='Compatibility'></a><h2>Compatibility</h2>
<p>&quot;=for testing&quot; and the associated modules and utilities are compatible
with Perl5 and most POD utilities.  They do not have to wait for
Perl6.  Its inclusion in the core is not mandatory and it can life
life as seperate utility if necessary (see below).</p>
<a name='Uses'></a><h2>Uses</h2>
<p>Embedded tests have obvious uses for module and program authors.  It
also has use in developing Perl.  Since the Perl C code contains POD,
tests can be embedded within same as anything else!</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>A Pod::Tests module need be written.  Its purpose is to scan the POD,
find the &quot;=for testing&quot; bits and organize them in some useful manner
for other utilities to use.  Pod::Tests can be written using Pod::Parser.</p>
<p>pod2tests will be a utility written using Pod::Tests.  It will take
the collected tests and generate the .t files.</p>
<p>Both Pod::Tests and pod2tests should be distributed with Perl for
maximum effectiveness.  However, should they not be distributed with
Perl, or should the module user have an older version of Perl,
embedded tests are still useful.  The module author will have to run
pod2tests before distributing their code and include the generated .t
file(s) in their distribution.  Current versions of Perl will run the
tests like any other.</p>
<p>Makemaker should be patched to be aware of pod2tests.  The generated
Makefile should run pod2tests similar to the way it runs pod2man.
However, should the patch not be accepted, the module author can
pregenerate the tests as above.</p>
<p>If Pod::Tests and pod2tests are accepted for the core, perlpod should
be patched to mention them.</p>
<a name='Problems'></a><h2>Problems</h2>
<ul>
<li><a name='scope'></a>scope</li>
<p>Each test block will be placed inside a block to attempt to protect
lexical context.</p>
<li><a name='editors'></a>editors</li>
<p>Editors may not recognize the =for testing block as perl code and will
not highlight syntax.  I have no solution for this.</p>
<li><a name='embedded vs .t'></a>embedded vs .t</li>
<p>This is not intended to replace hand-written .t files, but to augment
it.  Embedded tests will likely be short, specific tests.  Any larger
tests would be unwieldy to embed in the code and are more suited for
.t files.</p>
<li><a name='this isn't documentation'></a>this isn't documentation</li>
<p>POD stands for Plain Old Documentation.  Technically, tests are not
documentation.  In this sense, we are abusing POD a bit.  Oh well, its
not like any feature of Perl wasn't ever used for something its
designer didn't intend!</p>
</ul>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p><i><a href='http://search.cpan.org/perldoc?perlpod'>perlpod</a></i></p>
<p><i><a href='http://search.cpan.org/perldoc?Pod::Parser'>Pod::Parser</a></i></p>
</div>
